Combining Text and Bitmaps on Buttons

Description

It is often desirable to create a button with both text and a bitmap on the button. To mix text and an image on a button, you specify a special 'owner-draw' specification directive in the button's format specification.

It is referred to as an 'owner-draw' directive because the developer (i.e. the owner of the control, rather than Alpha Anywhere itself) specifies how the control is drawn.

A format string can take multiple directives delimited with semi-colons. The owner-draw specification is a second directive that is included in the format string. The syntax for an owner draw directive is:

O=specification

The specification controls the look of the button. In the following example we specify an image name, and an owner-draw specification in the button's format string, separated by a semi-colon. The following script produces a dialog with a button that has an image of a floppy disk (the built-in Alpha Anywhere image called "$a5_save"). The button also includes the text "Save File" on it.

result = ui_dlg_box("Bitmap and Text on a Button",<<%dlg%
File: [.64filename];
{lf};
<%I=$a5_save;O= {I=1} Save File;T=Save a file to disk%15,2!save_file> <10,2Close>
%dlg%,<<%code%
if (a_dlg_button = "save_file") then
    ui_msg_box("","")
    a_dlg_button = ""
end if
%code%)

This script produces the following dialog:

When the mouse is over the button, the bubble help 'Save a file to disk' is displayed.

Note that the size of the 'Save File' button is set to 15 characters by 1.5 lines. To make the size of the Cancel button look consistent, the height of this button is also set to 1.5 lines. Let's analyze how the owner-draw string in the above example works. We know we want the button to have the following format: (space) followed by (image) followed by (space) followed by (text: 'Save File') To specify that Alpha Anywhere should display an image, the first part of the owner-draw string is a space followed by:

{I=1}

This tells Alpha Anywhere to use the first image name in a list of image names specified in the 'I=imagename' directive. In this particular case this is a little redundant because only one image name was supplied ($a5_save). as we will see later on, there are situations in the case of list boxes, tree controls, and other control types, where it makes sense to specify more than one image name in the 'I=imagename' directive. Next, there is a space in the owner-draw string, which causes a space to display after the image. Finally, the text that appears on the button is specified ('Save File'). Putting this all together, we get:

O = {I=1} Save File

In addition to the owner-draw string there are two other aspects of the button specification that are worth noting. First, as the diagram above shows, when the mouse is over the button, the bubble help for the button is 'Save a file to disk'. This text is defined after the button size specification. Second, the event name that is generated when the button is pressed is specified by the '!save_file' directive. When the button is pressed, a_dlg_button is set to 'save_file'.

Justifying the Bitmap and Text

The button in the above dialog would look better if the bitmap and text were vertically centered. We can instruct Alpha Anywhere to center the bitmap and text in the button both vertically and horizontally by using the {J=C} directive in the owner draw string. The button syntax in the above script becomes:

<%I=$a5_save;O={J=C} {I=1} Save File ; %15,1.5Save a file to disk!save_file>

With this change to the owner-draw string, the dialog now looks like this: Buttons with Bitmap and Text-Center Justified

In addition to the {J=C} justification directive, there are other formatting directives that can be used in owner-draw strings. These are discussed in the next lesson.

Limitations

Desktop applications only.